refactor!: upgrade SDK to A2A 1.0 specs #572

muscariello · 2025-11-28T21:00:39Z

Summary

This PR migrates the a2a-python SDK from Pydantic-based types to protobuf-generated types, completing the upgrade to A2A v1.0. Fixes #559

Breaking Changes

Replace Pydantic-based type system with protobuf types from a2a_pb2
Update Part usage from Part(root=TextPart(text=...)) to Part(text=...)
Update Role enum from Role.user/Role.agent to Role.ROLE_USER/Role.ROLE_AGENT
Update TaskState enum to use TASK_STATE_* prefix

Changes

Update all source files to use proto types directly from a2a_pb2
Replace model_dump() with MessageToDict() for JSON serialization
Replace model_copy(deep=True) with CopyFrom() for proto cloning
Add new types module with proto imports and SDK-specific extras
Add proto_utils module with identity conversion utilities
Fix REST handler resource name formats for push notification configs
Fix gRPC handler to use SubscribeToTask instead of TaskSubscription
Fix database task store to handle proto objects from ORM
Update all test files for proto patterns and assertions
Fix spelling check failures by updating allow list
Fix inclusive language check failures:
- Replace master with main in documentation
- Rename Dummy classes to Mock in tests

Testing

601 tests passing
23 tests skipped (expected - require DB connections or cryptography deps)

BREAKING CHANGE: Replace Pydantic-based type system with protobuf types - Update all source files to use proto types directly from a2a_pb2 - Replace model_dump() with MessageToDict() for JSON serialization - Replace model_copy(deep=True) with CopyFrom() for proto cloning - Update Part usage from Part(root=TextPart(...)) to Part(text=...) - Update Role enum from Role.user to Role.ROLE_USER - Update TaskState enum to use TASK_STATE_* prefix - Add new types module with proto imports and SDK-specific extras - Add proto_utils module with identity conversion utilities - Fix REST handler resource name formats for push notification configs - Fix gRPC handler to use SubscribeToTask instead of TaskSubscription - Fix database task store to handle proto objects from ORM - Update all test files for proto patterns and assertions Tested: 601 tests passing, 23 skipped (expected - DB/crypto deps) Signed-off-by: Luca Muscariello <[email protected]>

gemini-code-assist · 2025-11-28T21:02:22Z

Summary of Changes

Hello @muscariello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request represents a foundational shift in the SDK's type system, moving from Pydantic models to native protobuf-generated types. This change aligns the SDK more closely with the A2A v1.0 specification, enhancing type consistency and performance. The migration necessitated extensive updates across the codebase, impacting how data is structured, serialized, and handled throughout the client and server components. While introducing several breaking changes to the API, the goal is to provide a more robust and future-proof foundation for A2A interactions.

Highlights

Protobuf Type Migration: The entire SDK has been migrated from Pydantic-based types to protobuf-generated types, completing the upgrade to A2A v1.0. This involves significant changes across client and server components to directly utilize protobuf messages.
Legacy Client Removal: The deprecated A2AClient (JSON-RPC) and A2AGrpcClient (gRPC) legacy client wrappers have been removed, streamlining the client API. Users should now use ClientFactory to create clients with specific transports.
API Changes and Breaking Changes: Key API changes include updating Part usage from Part(root=TextPart(text=...)) to Part(text=...), renaming Role enum values (e.g., Role.user to Role.ROLE_USER), and updating TaskState enum values with a TASK_STATE_* prefix. Method signatures across client transports and handlers have been updated to reflect the new protobuf request/response types.
Serialization and Deserialization: The internal serialization logic has been updated to use MessageToDict() for JSON serialization and ParseDict() for deserialization, replacing Pydantic's model_dump() and model_validate() methods. This ensures compatibility with protobuf messages.
Build and Configuration Updates: The buf.gen.yaml configuration has been updated to generate protobuf types into src/a2a/types instead of src/a2a/grpc. pyproject.toml and related linting/type-checking configurations (mypy, ruff) have been adjusted to exclude the new protobuf-generated files in their new location and to include the new json-rpc dependency.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This is a massive and well-executed refactoring to migrate the SDK from Pydantic types to protobuf-generated types, completing the upgrade to A2A v1.0. The changes are extensive, touching almost every part of the SDK, from client and server logic to transports, handlers, database models, and tests.

My review finds that the migration has been executed thoroughly and consistently. Key changes include:

Replacing Pydantic models with protobuf messages from a2a_pb2.
Updating data serialization from model_dump() to MessageToDict() and ParseDict().
Refactoring client transports (grpc, jsonrpc, rest) to work directly with protobuf types, which simplifies the code significantly.
Updating method signatures and data structures across the client and server components.
Introducing a new types module as a central place for all type definitions.
Removing legacy client implementations.

The overall quality of the changes is high. The code is now more aligned with the A2A v1.0 specification, and the gRPC transport, in particular, is much cleaner. The test suite has been updated to reflect these changes, with a large number of tests passing.

I have a few suggestions for improving code maintainability and simplifying the logic in the AuthInterceptor and the database task store. Otherwise, the PR looks excellent.

src/a2a/server/tasks/database_task_store.py

gemini-code-assist · 2025-11-28T21:05:37Z

src/a2a/server/tasks/database_task_store.py

    def _from_orm(self, task_model: TaskModel) -> Task:
-        """Maps a SQLAlchemy TaskModel to a Pydantic Task instance."""
-        # Map database columns to Pydantic model fields
+        """Maps a SQLAlchemy TaskModel to a Proto Task instance."""
+        # The ORM columns return proto objects for status, artifacts, history
+        # We need to convert them back to dicts for ParseDict
        task_data_from_db = {
            'id': task_model.id,
            'context_id': task_model.context_id,
-            'kind': task_model.kind,
-            'status': task_model.status,
-            'artifacts': task_model.artifacts,
-            'history': task_model.history,
-            'metadata': task_model.task_metadata,  # Map task_metadata column to metadata field
        }
-        # Pydantic's model_validate will parse the nested dicts/lists from JSON
-        return Task.model_validate(task_data_from_db)
+        # Add status if present (already a proto object from PydanticType)
+        if task_model.status is not None:
+            task_data_from_db['status'] = MessageToDict(task_model.status, preserving_proto_field_name=True)
+        # Add artifacts if present (list of proto objects)
+        if task_model.artifacts:
+            task_data_from_db['artifacts'] = [
+                MessageToDict(a, preserving_proto_field_name=True) if hasattr(a, 'DESCRIPTOR') else a
+                for a in task_model.artifacts
+            ]
+        # Add history if present (list of proto objects)
+        if task_model.history:
+            task_data_from_db['history'] = [
+                MessageToDict(m, preserving_proto_field_name=True) if hasattr(m, 'DESCRIPTOR') else m
+                for m in task_model.history
+            ]
+        # Add metadata if present
+        if task_model.task_metadata is not None:
+            task_data_from_db['metadata'] = task_model.task_metadata
+        # Use ParseDict to create proto from dict
+        return ParseDict(task_data_from_db, Task())


This function seems overly complex. Since PydanticType and PydanticListType already deserialize the JSON from the database into protobuf message objects, you can construct the final Task protobuf object directly using these objects, rather than converting them back to dictionaries and then parsing the whole dictionary again. This would be more efficient and easier to read.

def _from_orm(self, task_model: TaskModel) -> Task: """Maps a SQLAlchemy TaskModel to a Proto Task instance.""" task = Task( id=task_model.id, context_id=task_model.context_id, ) if task_model.status: task.status.CopyFrom(task_model.status) if task_model.artifacts: task.artifacts.extend(task_model.artifacts) if task_model.history: task.history.extend(task_model.history) if task_model.task_metadata: task.metadata.update(task_model.task_metadata) return task

gemini-code-assist · 2025-11-28T21:05:37Z

src/a2a/client/auth/interceptor.py

+    which = scheme.WhichOneof('scheme')
+    if which == 'api_key_security_scheme':
+        return scheme.api_key_security_scheme
+    elif which == 'http_auth_security_scheme':
+        return scheme.http_auth_security_scheme
+    elif which == 'oauth2_security_scheme':
+        return scheme.oauth2_security_scheme
+    elif which == 'open_id_connect_security_scheme':
+        return scheme.open_id_connect_security_scheme
+    elif which == 'mtls_security_scheme':
+        return scheme.mtls_security_scheme
+    return None


This function can be simplified by using getattr to dynamically access the oneof field. This makes the code more concise and easier to maintain if more security schemes are added in the future.

which = scheme.WhichOneof('scheme') if which: return getattr(scheme, which) return None

- Fix agent_app.py Part access pattern for proto (HasField/direct access) - Fix ClientEvent handling in E2E tests (StreamResponse, not Task) - Fix notifications_app.py to serialize proto Task to dict - Update SetTaskPushNotificationConfigRequest interface in handlers - Update default_request_handler to use request.parent instead of name - Update jsonrpc_handler to pass full request to handler - Update unit tests to use SetTaskPushNotificationConfigRequest Signed-off-by: Luca Muscariello <[email protected]>

Tehsmash · 2025-12-01T10:07:00Z

buf.gen.yaml

 inputs:
  - git_repo: https://github.com/a2aproject/A2A.git
-    ref: main
+    ref: transports


We need to change this back to "main" to pick up the latest fixes from the a2a.proto and before we merge we need to switch to the tag for v1.0 (when its cut)

src/a2a/client/auth/interceptor.py

Tehsmash · 2025-12-01T11:17:25Z

src/a2a/types/extras.py

+
+# Alias for backward compatibility - the proto uses SendMessageRequest
+# where old code might use MessageSendParams
+from a2a.types.a2a_pb2 import SendMessageRequest as MessageSendParams


Lets not do this, any code that is already using a2a.types.MessageSendParams would need change the imports anyway and I think this will be confusing.

this is a quick removal that in any case is supposed to be removed before the PR is complete.

Tehsmash · 2025-12-01T11:18:01Z

src/a2a/types/extras.py

+)
+
+# Alias for streaming - same as SendMessageRequest in the proto
+SendStreamingMessageRequest = SendMessageRequest = MessageSendParams


-1, lets just update the code to use SendMessageRequest.

Tehsmash · 2025-12-01T11:19:40Z

src/a2a/types/extras.py

+    """Transport protocol string constants for backward compatibility."""
+    jsonrpc = "JSONRPC"
+    http_json = "HTTP+JSON"
+    grpc = "GRPC"


In the client code I add these as constants, if we want to put them somewhere common I would add a "constants.py" / constants module outside of "types".

To move this elsewhere I would have to solve a circular dependency first. There needs to be additional refactoring work before I can do that.

I am moving things from the refactor out of extras.py until it is empty. Then I will remove the file. A few more commits I think.

Tehsmash · 2025-12-01T11:22:40Z

src/a2a/types/extras.py

+# Union of all A2A error types
+A2AError = Union[
+    JSONRPCError,
+    JSONParseError,
+    InvalidRequestError,
+    MethodNotFoundError,
+    InvalidParamsError,
+    InternalError,
+    TaskNotFoundError,
+    TaskNotCancelableError,
+    PushNotificationNotSupportedError,
+    UnsupportedOperationError,
+    ContentTypeNotSupportedError,
+    InvalidAgentResponseError,
+    AuthenticatedExtendedCardNotConfiguredError,
+]
+
+
+class JSONRPCRequest(A2ABaseModel):
+    """Represents a JSON-RPC 2.0 Request object."""
+
+    jsonrpc: Literal["2.0"] = "2.0"
+    method: str
+    params: Any | None = None
+    id: str | int | None = None
+
+
+class JSONRPCResponse(A2ABaseModel):
+    """Represents a JSON-RPC 2.0 Success Response object."""
+
+    jsonrpc: Literal["2.0"] = "2.0"
+    result: Any
+    id: str | int | None = None
+
+
+class JSONRPCErrorResponse(A2ABaseModel):
+    """Represents a JSON-RPC 2.0 Error Response object."""
+
+    jsonrpc: Literal["2.0"] = "2.0"
+    error: A2AError
+    id: str | int | None = None
+
+
+# Type alias for A2A requests (union of all request types)
+# This maps to the various request message types in the proto
+from a2a.types.a2a_pb2 import (
+    CancelTaskRequest,
+    GetExtendedAgentCardRequest,
+    GetTaskPushNotificationConfigRequest,
+    GetTaskRequest,
+    SendMessageRequest,
+    SetTaskPushNotificationConfigRequest,
+    SubscribeToTaskRequest,
+)
+
+A2ARequest = Union[
+    SendMessageRequest,
+    GetTaskRequest,
+    CancelTaskRequest,
+    SetTaskPushNotificationConfigRequest,
+    GetTaskPushNotificationConfigRequest,
+    SubscribeToTaskRequest,
+    GetExtendedAgentCardRequest,
+]
+
+
+# JSON-RPC Success Response types
+# These wrap the result of successful RPC calls
+# Note: result is typed as Any to allow both proto messages and dicts
+class GetTaskSuccessResponse(A2ABaseModel):
+    """Success response for GetTask RPC."""
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: str | int | None = None
+    result: Any
+
+
+class CancelTaskSuccessResponse(A2ABaseModel):
+    """Success response for CancelTask RPC."""
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: str | int | None = None
+    result: Any
+
+
+class SendMessageSuccessResponse(A2ABaseModel):
+    """Success response for SendMessage RPC."""
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: str | int | None = None
+    result: Any
+
+
+class SendStreamingMessageSuccessResponse(A2ABaseModel):
+    """Success response for streaming message RPC."""
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: str | int | None = None
+    result: Any  # Streaming events
+
+
+class SetTaskPushNotificationConfigSuccessResponse(A2ABaseModel):
+    """Success response for SetTaskPushNotificationConfig RPC."""
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: str | int | None = None
+    result: Any
+
+
+class GetTaskPushNotificationConfigSuccessResponse(A2ABaseModel):
+    """Success response for GetTaskPushNotificationConfig RPC."""
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: str | int | None = None
+    result: Any
+
+
+class ListTaskPushNotificationConfigSuccessResponse(A2ABaseModel):
+    """Success response for ListTaskPushNotificationConfig RPC."""
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: str | int | None = None
+    result: Any
+
+
+class DeleteTaskPushNotificationConfigSuccessResponse(A2ABaseModel):
+    """Success response for DeleteTaskPushNotificationConfig RPC."""
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: str | int | None = None
+    result: None = None
+
+
+class GetAuthenticatedExtendedCardSuccessResponse(A2ABaseModel):
+    """Success response for GetAuthenticatedExtendedCard RPC."""
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: str | int | None = None
+    result: Any  # AgentCard


Let not add our own implementation of this. In the client code I pull in the "jsonrpc" package from pypi, which has the JSONRPC20Response type already defined, then we only need to concern ourselves with populating the result or error fields.

src/a2a/server/apps/jsonrpc/fastapi_app.py

src/a2a/server/apps/jsonrpc/jsonrpc_app.py

Tehsmash · 2025-12-01T11:52:52Z

src/a2a/server/apps/jsonrpc/jsonrpc_app.py

    JSONRPCError,
    JSONRPCErrorResponse,
    JSONRPCRequest,
    JSONRPCResponse,


Lets pull in the jsonrpc dependency so that we can remove these from the types.

src/a2a/server/apps/jsonrpc/jsonrpc_app.py

Tehsmash · 2025-12-01T12:29:55Z

src/a2a/server/request_handlers/default_request_handler.py

        """
        # Create task manager and validate existing task
+        # Proto empty strings should be treated as None
+        task_id = params.request.task_id or None


Need to confirm if "task_id" should be just the UUID, or should be in the form "tasks/".
I think AIP for this said that it should be "tasks/" because this is the FQN for the task.

src/a2a/utils/error_handlers.py

Tehsmash · 2025-12-01T15:09:42Z

src/a2a/utils/parts.py

        A list of dictionaries containing the data from any `DataPart` objects found.
    """
-    return [part.root.data for part in parts if isinstance(part.root, DataPart)]
+    from google.protobuf.json_format import MessageToDict


No need for an inline import, lets move this to the top of the file.

src/a2a/utils/proto_utils.py

src/a2a/utils/task.py

- Fix E402: Move telemetry import to top in default_request_handler.py - Fix TRY300/RET504: Return directly in grpc_handler.py try blocks - Fix TRY004: Add noqa for valid ValueError in database_push_notification_config_store.py - Fix pyright: Add else branch for unbound client_event in base_client.py - Fix pyright: Add cast for rpc_request.data in jsonrpc.py transport All linter checks now pass: - ruff check: 0 errors - ruff format: 78 files formatted - mypy: 0 errors in 78 files - pyright: 0 errors, 0 warnings All 730 tests pass (including PostgreSQL and MySQL database tests)

Tehsmash · 2025-12-01T15:24:44Z

src/a2a/client/auth/interceptor.py

+

-def _get_security_scheme_value(scheme: SecurityScheme):
+def _get_security_scheme_value(scheme: SecurityScheme) -> _SecuritySchemeValue:


I think this change has just proven my point about moving this inline in the function below and changing how the "match" is done.

Tehsmash · 2025-12-01T15:58:23Z

src/a2a/server/tasks/task_manager.py

                task.history.append(task.status.message)
            if event.metadata:
-                task.metadata.update(event.metadata)
+                task.metadata.update(dict(event.metadata))  # type: ignore[arg-type]


We should use task.metadata.MergeFrom/CopyFrom here depending on the desired behaviour

I will avoid casting

…ry directly - Update JSONRPCHandler to return dict[str, Any] instead of Pydantic RootModels - Update response_helpers to build dicts with JSON-RPC 2.0 structure - Remove unused Pydantic response types from types module - Fix proto dependency loading in a2a_pb2.py - Update all tests to check dict responses instead of Pydantic models - Add TransportProtocol constants to utils module

…iases - Rename on_resubscribe_to_task to on_subscribe_to_task across all handlers - Update METHOD_TO_MODEL with gRPC-style method names (SendMessage, GetTask, etc.) - Update JSON-RPC client to use new method names - Fix ListTaskPushNotificationConfigResponse to use 'configs' field - Remove TaskResubscriptionRequest alias from extras.py - Update TransportProtocol imports to use a2a.utils.constants - Fix on_get_task_push_notification_config params type - Update all tests for new method names and response types

…s.py - Moved all error type definitions (JSONRPCError, A2AError, etc.) to utils/errors.py - Updated all imports across 15 files to use a2a.utils.errors - Defined A2ARequest union inline in types/__init__.py - Deleted the now-redundant extras.py file - Re-exported error types from types/__init__.py for public API

src/a2a/client/auth/interceptor.py

Tehsmash · 2025-12-02T15:09:12Z

src/a2a/utils/errors.py

+class A2ABaseModel(BaseModel):
+    """Base model for all A2A SDK types."""
+
+    model_config = {
+        'extra': 'allow',
+        'populate_by_name': True,
+        'arbitrary_types_allowed': True,
+    }
+
+
+# JSON-RPC Error types - A2A specific error codes
+class JSONRPCError(A2ABaseModel):
+    """Represents a JSON-RPC 2.0 Error object."""
+
+    code: int
+    """A number that indicates the error type that occurred."""
+    message: str
+    """A string providing a short description of the error."""
+    data: Any | None = None
+    """Additional information about the error."""
+
+
+class JSONParseError(A2ABaseModel):
+    """JSON-RPC parse error (-32700)."""
+
+    code: Literal[-32700] = -32700
+    message: str = 'Parse error'
+    data: Any | None = None
+
+
+class InvalidRequestError(A2ABaseModel):
+    """JSON-RPC invalid request error (-32600)."""
+
+    code: Literal[-32600] = -32600
+    message: str = 'Invalid Request'
+    data: Any | None = None
+
+
+class MethodNotFoundError(A2ABaseModel):
+    """JSON-RPC method not found error (-32601)."""
+
+    code: Literal[-32601] = -32601
+    message: str = 'Method not found'
+    data: Any | None = None
+
+
+class InvalidParamsError(A2ABaseModel):
+    """JSON-RPC invalid params error (-32602)."""
+
+    code: Literal[-32602] = -32602
+    message: str = 'Invalid params'
+    data: Any | None = None
+
+
+class InternalError(A2ABaseModel):
+    """JSON-RPC internal error (-32603)."""
+
+    code: Literal[-32603] = -32603
+    message: str = 'Internal error'
+    data: Any | None = None
+
+
+class TaskNotFoundError(A2ABaseModel):
+    """A2A-specific error for task not found (-32001)."""
+
+    code: Literal[-32001] = -32001
+    message: str = 'Task not found'
+    data: Any | None = None
+
+
+class TaskNotCancelableError(A2ABaseModel):
+    """A2A-specific error for task not cancelable (-32002)."""
+
+    code: Literal[-32002] = -32002
+    message: str = 'Task cannot be canceled'
+    data: Any | None = None
+
+
+class PushNotificationNotSupportedError(A2ABaseModel):
+    """A2A-specific error for push notification not supported (-32003)."""
+
+    code: Literal[-32003] = -32003
+    message: str = 'Push Notification is not supported'
+    data: Any | None = None
+
+
+class UnsupportedOperationError(A2ABaseModel):
+    """A2A-specific error for unsupported operation (-32004)."""
+
+    code: Literal[-32004] = -32004
+    message: str = 'This operation is not supported'
+    data: Any | None = None
+
+
+class ContentTypeNotSupportedError(A2ABaseModel):
+    """A2A-specific error for content type not supported (-32005)."""
+
+    code: Literal[-32005] = -32005
+    message: str = 'Incompatible content types'
+    data: Any | None = None
+
+
+class InvalidAgentResponseError(A2ABaseModel):
+    """A2A-specific error for invalid agent response (-32006)."""
+
+    code: Literal[-32006] = -32006
+    message: str = 'Invalid agent response'
+    data: Any | None = None
+
+
+class AuthenticatedExtendedCardNotConfiguredError(A2ABaseModel):
+    """A2A-specific error for authenticated extended card not configured (-32007)."""
+
+    code: Literal[-32007] = -32007
+    message: str = 'Authenticated Extended Card is not configured'
+    data: Any | None = None


The A2A exception's here shouldn't have JSONRPC specific data, the JSONRPC server/client components should have a map from the exceptions to the JSONRPC code and vice-versa for raising an exception on receipt of a JSONRPCError

JSONRPC specific exceptions like MethodNotFound should live in the JSONRPC implementation code or a separate JSONRPC common package IMO.

still relevant

src/a2a/utils/error_handlers.py

src/a2a/server/apps/jsonrpc/jsonrpc_app.py

Tehsmash · 2025-12-02T16:19:38Z

src/a2a/server/request_handlers/request_handler.py

    async def on_resubscribe_to_task(
        self,
-        params: TaskIdParams,
+        params: CancelTaskRequest,


Tehsmash · 2025-12-02T16:20:41Z

src/a2a/server/models.py

+        if isinstance(self.pydantic_type, type) and issubclass(self.pydantic_type, ProtoMessage):
+            return ParseDict(value, self.pydantic_type())  # type: ignore[return-value]
+        # Assume it's a Pydantic model
+        return self.pydantic_type.model_validate(value)  # type: ignore[union-attr]


I think this is still relevant to models.py even though its been disconnected. You can resolve this and I'll open a new comment.

Tehsmash · 2025-12-02T16:20:54Z

src/a2a/server/models.py

No need to support Pydantic here IMO, just need to support the protobuf types.

One thought: We need to understand if we need to support old messages/tasks stored in the DB and translate them to the protobuf types. Otherwise we may require people to drop the DBs for their Agents

Tehsmash · 2025-12-02T16:21:56Z

src/a2a/utils/parts.py

        A list of dictionaries containing the data from any `DataPart` objects found.
    """
-    return [part.root.data for part in parts if isinstance(part.root, DataPart)]
+    from google.protobuf.json_format import MessageToDict


src/a2a/utils/proto_utils.py

# Description Refine error management for the streaming operation. Previously, errors were converted into stream parts, resulting in the loss of status info. The updated logic now first verifies if the request was successful; if it failed, a client error is returned, preserving the relevant status information. - [x] Follow the [`CONTRIBUTING` Guide](https://github.com/a2aproject/a2a-python/blob/main/CONTRIBUTING.md). - [x] Make your Pull Request title in the <https://www.conventionalcommits.org/> specification. - Important Prefixes for [release-please](https://github.com/googleapis/release-please): - `fix:` which represents bug fixes, and correlates to a [SemVer](https://semver.org/) patch. - `feat:` represents a new feature, and correlates to a SemVer minor. - `feat!:`, or `fix!:`, `refactor!:`, etc., which represent a breaking change (indicated by the `!`) and will result in a SemVer major. - [x] Ensure the tests and linter pass (Run `bash scripts/format.sh` from the repository root to format) - [x] Appropriate docs were updated (if necessary) Fixes a2aproject#502 🦕

🤖 I have created a release *beep* *boop* --- ## [0.3.20](a2aproject/a2a-python@v0.3.19...v0.3.20) (2025-12-03) ### Bug Fixes * Improve streaming errors handling ([a2aproject#576](a2aproject#576)) ([7ea7475](a2aproject@7ea7475)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

muscariello · 2025-12-04T08:01:43Z

@Tehsmash I am going to wait a few more days for the A2A 1.0 specs to get the most recent updates.

# Description Just fixing various typos discovered while reading code of the repo: see commit diffs for details Cheers Didier - [X] Follow the [`CONTRIBUTING` Guide](https://github.com/a2aproject/a2a-python/blob/main/CONTRIBUTING.md). - [X] Make your Pull Request title in the <https://www.conventionalcommits.org/> specification. - [X] Ensure the tests and linter pass (Run `bash scripts/format.sh` from the repository root to format) - [X] Appropriate docs were updated (if necessary) Fixes #<issue_number_goes_here> 🦕 N/A --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

…ect#581) This PR introduces digital signatures for Agent Cards to ensure authenticity and integrity, adhering to the A2A specification for [Agent Card Signing (Section 8.4).](https://a2a-protocol.org/latest/specification/#84-agent-card-signing) ## Changes: - Implement `Canonicalization` Logic (`src/a2a/utils/signing.py`) - Add `Signing` and `Verification` Utilities (`src/a2a/utils/signing.py`): - `create_agent_card_signer` which generates an `agent_card_signer` for signing `AgentCards` - `create_signature_verifier` which generates a `signature_verifier` for verification of `AgentCard` signatures - Enable signature verification support for `json-rpc`, `rest` and `gRPC` transports - Add Protobuf Conversion for Signatures (`src/a2a/utils/proto_utils.py`) ensuring `AgentCardSignature` can be serialized and deserialized for gRPC transport - Add related tests: - integration tests for fetching signed cards from the Server - unit tests for signing util - unit tests for protobuf conversions - [x] Follow the [`CONTRIBUTING` Guide](https://github.com/a2aproject/a2a-python/blob/main/CONTRIBUTING.md). - [x] Make your Pull Request title in the <https://www.conventionalcommits.org/> specification. - Important Prefixes for [release-please](https://github.com/googleapis/release-please): - `fix:` which represents bug fixes, and correlates to a [SemVer](https://semver.org/) patch. - `feat:` represents a new feature, and correlates to a SemVer minor. - `feat!:`, or `fix!:`, `refactor!:`, etc., which represent a breaking change (indicated by the `!`) and will result in a SemVer major. - [x] Ensure the tests and linter pass (Run `bash scripts/format.sh` from the repository root to format) - [x] Appropriate docs were updated (if necessary) Release-As: 0.3.21

# Description Read further and discovered this additional (and final) set of typos

muscariello · 2026-01-16T23:11:43Z

@lkawka I will go through all the remaining comments on Monday. Thanks for the review.

muscariello · 2026-01-17T08:21:16Z

@Tehsmash could you please check again? I am going to recheck all the previous comments on Monday but please recheck as well. I included the latest updates based on the merge queue in the spec based on the latest TSC votes. We'll see on Tue if the spec can be considered complete for v1.
We could also merge this one and propose another PR after to avoid conflicts.

Signed-off-by: Luca Muscariello <[email protected]>

Tehsmash · 2026-01-19T14:01:13Z

scripts/grpc_gen_post_processor.py

This should be removed as its a left over.

src/a2a/client/auth/interceptor.py

Tehsmash · 2026-01-19T14:06:22Z

src/a2a/client/transports/jsonrpc.py

        elif agent_card:
-            self.url = agent_card.url
+            if agent_card.supported_interfaces:
+                self.url = agent_card.supported_interfaces[0].url


I don't think we can assume that supported_interfaces[0] is JSONRPC, we need logic like we have in "rest.py" which checks the interface type and pulls out the first JSONRPC type.

It would probably make sense to have a common function (if there isn't one already) which finds the first supported_interface of a given type and returns it.

Tehsmash · 2026-01-19T14:51:08Z

src/a2a/client/base_client.py

+            # Proto3 doesn't support HasField for scalars, so MergeFrom won't
+            # override with default values (e.g. False). We explicitly set it here
+            # assuming configuration is authoritative.
+            config.blocking = configuration.blocking


This seems weird to me. I think it might really be a bug in the a2a.proto.

https://protobuf.dev/programming-guides/field_presence/#presence-proto3

This default behavior of not tracking presence without the optional label is different from the proto2 behavior. We recommend using the optional label with proto3 unless you have a specific reason not to.

This enables explict presence, in the next versions of Proto, "editions", they go back to having explict presense with out the "optional" flag.

With the "optional" flag set in the proto, "MergeFrom" works as expected:

$ uv run src/protobooleanmerge/test.py Thing1 HasField(blocking): True Value: False Thing2 HasField(blocking): True Value: True After MergeFrom: Thing2 HasField(blocking): True Value: False

Tehsmash · 2026-01-19T15:25:18Z

src/a2a/client/client_factory.py

                if x in client_set:
                    transport_protocol = x
                    transport_url = url
                    break


I think we need to adjust this logic, at the moment the "server_set" will build a map keeping the last (therefore least preferential) supported_interface for each protocol_binding type the server specifies.

In the spec you can have multiple interface of the same protocol_binding type (i.e. 2 JSONRPC interfaces) so that you can have say a preferred higher bandwidth option and a lower bandwidth option as fail over.

For simplicity we should probably just take the first item in the card's supported interface which is in the supported_protocol_bindings list something like:

for supported_interface in card.supported_interfaces: if supported_interface.protocol_binding in self._config.supported_protocol_bindings: transport_protocol = x transport_url = supported_interface.url break

For the client preference mode we can do:

for protocol_binding in self._config.supported_protocol_bindings: supported_interface = next([si for si in card.supported_interfaces if si.protocol_binding == protocol_binding], None) if supported_interface != None: transport_protocol = x transport_url = supported_interface.url break

Tehsmash · 2026-01-19T16:06:09Z

src/a2a/server/tasks/base_push_notification_sender.py

            response = await self._client.post(
                url,
-                json=task.model_dump(mode='json', exclude_none=True),
+                json=MessageToDict(task),


still relevant

Tehsmash · 2026-01-19T16:12:03Z

src/a2a/client/client_factory.py


+TRANSPORT_PROTOCOLS_JSONRPC = 'JSONRPC'
+TRANSPORT_PROTOCOLS_GRPC = 'GRPC'
+TRANSPORT_PROTOCOLS_HTTP_JSON = 'HTTP+JSON'


We can use the constants that are now defined in utils/constants.py

Tehsmash · 2026-01-19T16:13:17Z

src/a2a/utils/errors.py

+class A2ABaseModel(BaseModel):
+    """Base model for all A2A SDK types."""
+
+    model_config = {
+        'extra': 'allow',
+        'populate_by_name': True,
+        'arbitrary_types_allowed': True,
+    }
+
+
+# JSON-RPC Error types - A2A specific error codes
+class JSONRPCError(A2ABaseModel):
+    """Represents a JSON-RPC 2.0 Error object."""
+
+    code: int
+    """A number that indicates the error type that occurred."""
+    message: str
+    """A string providing a short description of the error."""
+    data: Any | None = None
+    """Additional information about the error."""
+
+
+class JSONParseError(A2ABaseModel):
+    """JSON-RPC parse error (-32700)."""
+
+    code: Literal[-32700] = -32700
+    message: str = 'Parse error'
+    data: Any | None = None
+
+
+class InvalidRequestError(A2ABaseModel):
+    """JSON-RPC invalid request error (-32600)."""
+
+    code: Literal[-32600] = -32600
+    message: str = 'Invalid Request'
+    data: Any | None = None
+
+
+class MethodNotFoundError(A2ABaseModel):
+    """JSON-RPC method not found error (-32601)."""
+
+    code: Literal[-32601] = -32601
+    message: str = 'Method not found'
+    data: Any | None = None
+
+
+class InvalidParamsError(A2ABaseModel):
+    """JSON-RPC invalid params error (-32602)."""
+
+    code: Literal[-32602] = -32602
+    message: str = 'Invalid params'
+    data: Any | None = None
+
+
+class InternalError(A2ABaseModel):
+    """JSON-RPC internal error (-32603)."""
+
+    code: Literal[-32603] = -32603
+    message: str = 'Internal error'
+    data: Any | None = None
+
+
+class TaskNotFoundError(A2ABaseModel):
+    """A2A-specific error for task not found (-32001)."""
+
+    code: Literal[-32001] = -32001
+    message: str = 'Task not found'
+    data: Any | None = None
+
+
+class TaskNotCancelableError(A2ABaseModel):
+    """A2A-specific error for task not cancelable (-32002)."""
+
+    code: Literal[-32002] = -32002
+    message: str = 'Task cannot be canceled'
+    data: Any | None = None
+
+
+class PushNotificationNotSupportedError(A2ABaseModel):
+    """A2A-specific error for push notification not supported (-32003)."""
+
+    code: Literal[-32003] = -32003
+    message: str = 'Push Notification is not supported'
+    data: Any | None = None
+
+
+class UnsupportedOperationError(A2ABaseModel):
+    """A2A-specific error for unsupported operation (-32004)."""
+
+    code: Literal[-32004] = -32004
+    message: str = 'This operation is not supported'
+    data: Any | None = None
+
+
+class ContentTypeNotSupportedError(A2ABaseModel):
+    """A2A-specific error for content type not supported (-32005)."""
+
+    code: Literal[-32005] = -32005
+    message: str = 'Incompatible content types'
+    data: Any | None = None
+
+
+class InvalidAgentResponseError(A2ABaseModel):
+    """A2A-specific error for invalid agent response (-32006)."""
+
+    code: Literal[-32006] = -32006
+    message: str = 'Invalid agent response'
+    data: Any | None = None
+
+
+class AuthenticatedExtendedCardNotConfiguredError(A2ABaseModel):
+    """A2A-specific error for authenticated extended card not configured (-32007)."""
+
+    code: Literal[-32007] = -32007
+    message: str = 'Authenticated Extended Card is not configured'
+    data: Any | None = None


still relevant

Tehsmash · 2026-01-19T16:16:39Z

src/a2a/utils/parts.py

Be aware this will change if Darrel's "Part" proposal merges.

src/a2a/utils/task.py

Co-authored-by: Sam Betts <[email protected]>

- Fix client factory transport preference selection - Update proto handling to use MergeFrom/CopyFrom correctly - Remove preserving_proto_field_name from MessageToDict - Fix history length limiting logic - Improve SendMessageResponse construction in handler Signed-off-by: Luca Muscariello <[email protected]>

Signed-off-by: Luca Muscariello <[email protected]>

Co-authored-by: Sam Betts <[email protected]>

…dler Signed-off-by: Luca Muscariello <[email protected]>

Signed-off-by: Luca Muscariello <[email protected]>

- Create `src/a2a/server/jsonrpc_models.py` to hold exception classes. - Remove `src/a2a/server/apps/jsonrpc/errors.py`. - Update imports across server handlers, utils, and tests. - Fix logic in DefaultRequestHandler.on_get_task_push_notification_config to handle list of configs.

- Configure buf.gen.yaml with openapiv2 to generate Swagger 2.0 spec. - Configure pyproject.toml with hatch-build-scripts to run generation. - Add scripts/gen_proto.sh to handle generation and fix gRPC imports. - Update FastAPI app to load generated a2a.json. - Update tests to accommodate Swagger 2.0 schema structure. - Add a2a.json to gitignore. Signed-off-by: Luca Muscariello <[email protected]>

Signed-off-by: Luca Muscariello <[email protected]>

Tehsmash and others added 2 commits November 21, 2025 17:02

[DRAFT] feat: Upgrade A2A to v1.0

b348735

This updates the SDK to be A2A v1.0 compliant, all types are generated from the v1.0 a2a.proto. JSONRPC/HTTP+JSON transports are converted to use the a2a types encoded using ProtoJSON directly from the generated types.

muscariello requested review from a team and a2a-bot as code owners November 28, 2025 21:00

gemini-code-assist bot reviewed Nov 28, 2025

View reviewed changes

muscariello mentioned this pull request Nov 30, 2025

[DRAFT] feat!: Upgrade A2A to v1.0 #556

Closed

4 tasks

muscariello added this to TSC Review Nov 30, 2025

github-project-automation bot moved this to Backlog in TSC Review Nov 30, 2025

Tehsmash suggested changes Dec 1, 2025

View reviewed changes

muscariello marked this pull request as draft December 1, 2025 13:53

Tehsmash suggested changes Dec 1, 2025

View reviewed changes

muscariello changed the title ~~feat!: Migrate from Pydantic types to protobuf-generated types~~ feat!: upgrade SDK to A2A 1.0 specs Dec 1, 2025

Tehsmash reviewed Dec 1, 2025

View reviewed changes

holtskinner changed the title ~~feat!: upgrade SDK to A2A 1.0 specs~~ refactor!: upgrade SDK to A2A 1.0 specs Dec 1, 2025

muscariello added 3 commits December 1, 2025 20:04

chore: remove AIP-discussion-response.md from tracking

ac1050d

Tehsmash reviewed Dec 2, 2025

View reviewed changes

holtskinner changed the base branch from main to 1.0-a2a_proto_refactor December 2, 2025 16:49

holtskinner requested a review from lkawka December 2, 2025 16:50

lkawka and others added 2 commits December 3, 2025 15:52

didier-durand and others added 3 commits December 12, 2025 14:12

chore: Fixing typos (final round) (a2aproject#588)

090ca9c

# Description Read further and discovered this additional (and final) set of typos

muscariello marked this pull request as ready for review January 16, 2026 23:10

style: fix spelling errors and add words to allow list

0ae8548

muscariello requested a review from Tehsmash January 17, 2026 08:18

muscariello added 4 commits January 17, 2026 09:26

style: add more tech terms to spelling allow list

bd552f6

style: fix spelling of interruptible

d8df048

build(spelling): exclude generated protobuf types from spell check

7433e04

fix: replace non-inclusive language in optionals.py

8e5ab33

Signed-off-by: Luca Muscariello <[email protected]>

muscariello force-pushed the a2a_proto_refactor branch from 67f27a8 to 8e5ab33 Compare January 17, 2026 15:59

chore: remove unused type generation scripts and deps

ce4c828

Tehsmash reviewed Jan 19, 2026

View reviewed changes

muscariello and others added 17 commits January 20, 2026 17:53

Apply suggestions from code review

66073cf

Co-authored-by: Sam Betts <[email protected]>

Apply suggestion from @Tehsmash

d7fb690

Co-authored-by: Sam Betts <[email protected]>

fix(client): respect blocking configuration in send_message

3eeea28

Signed-off-by: Luca Muscariello <[email protected]>

refactor: decouple JSON-RPC errors and fix circular imports

796d86b

Signed-off-by: Luca Muscariello <[email protected]>

Apply suggestion from @Tehsmash

913234c

Co-authored-by: Sam Betts <[email protected]>

fix(server): add missing StreamResponse import in default_request_han…

6260ea2

…dler Signed-off-by: Luca Muscariello <[email protected]>

fix(server): wrap task in StreamResponse for push notifications

c00b7b8

Signed-off-by: Luca Muscariello <[email protected]>

Docs: Clarify Proto3 repeated field presence checks in AuthInterceptor

33d3232

chore: fix inclusive language and spelling check failures

51ec5e9

Signed-off-by: Luca Muscariello <[email protected]>

chore: update spelling allow list and excludes

6ea324b

Signed-off-by: Luca Muscariello <[email protected]>

chore: add a2a-specific terms to spelling allow list

688e2c2

Signed-off-by: Luca Muscariello <[email protected]>

chore: add remaining unrecognized words to allow list

e9152ab

Signed-off-by: Luca Muscariello <[email protected]>

chore: replace master with main in documentation URLs

c6d97fd

Signed-off-by: Luca Muscariello <[email protected]>

chore: sort spelling allow list

cd8946b

Signed-off-by: Luca Muscariello <[email protected]>

Tehsmash approved these changes Jan 21, 2026

View reviewed changes



		def _get_security_scheme_value(scheme: SecurityScheme):
		def _get_security_scheme_value(scheme: SecurityScheme) -> _SecuritySchemeValue:

refactor!: upgrade SDK to A2A 1.0 specs #572

Are you sure you want to change the base?

refactor!: upgrade SDK to A2A 1.0 specs #572

Conversation

muscariello commented Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking Changes

Changes

Testing

Related

Uh oh!

gemini-code-assist bot commented Nov 28, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

gemini-code-assist bot Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

muscariello Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

muscariello commented Nov 28, 2025 •

edited

Loading

muscariello Jan 19, 2026 •

edited

Loading